<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Installation | Rho Framework Docs</title>
<meta name="description" value="Installation - Documentation for the Rho PHP Framework" />
<meta name="keywords" value="rho, framework, php, docs, documentation, help, examples" />
<link href="docs.css" rel="stylesheet" type="text/css" />
<link rel="shortcut icon" href="favicon.ico" />
</head>
<body>
<!-- header -->
<div id="byline">ρ Rho Framework Documentation</div>
<h1>Installation</h1>
<p>First, make sure you meet the <a href="requirements.html">server requirements</a>.</p>

<p>Through-out this documentation, references will be made to the development server and the production server:</p>
<dl>
  <dt><em>Development Server</em></dt>
  <dd>The machine you'll be working on when writing your application.  Normally your workstation, often accessed as <span class="url">localhost</span>.</dd>
  <dt><em>Production Server</em></dt>
  <dd>The web server where the website will be hosted when it's finished, 
  acessed as <span class="url">www.example.net</span>.</dd>
</dl>

<h3>Extract the Archive</h3>
<p>Extract the rho archive you downloaded into your development server.  There are 3 main directories.

<a name="dir_srtuct"> </a>
<h2>Directory Structure</h2>
<dl>
  <dt><span class="file">app/</span></dt>
  <dd>Application folder.  Contains sub-directories for your application's configuration, language strings, logs, models, views, etc.  Normally is above the web server document root.</dd>

  <dt><span class="file">rho/</span></dt>
  <dd>Contains the Rho framework, including 3rd party libraries. Normally is above the web server document root.</dd>

  <dt><span class="file">www/</span></dt>
  <dd>Web files folder.  The <strong>contents</strong> of this folder live inside the document root.
  As well as image and javascript files, contains a sample <span class="file">.htacess</span> file, and 
  <span class="file">_dispatch.php</span> used to dispatch the controllers. <br />
  <strong>This is also where your controller files will be</strong>.
  This is different to other frameworks you may have used in the past.</dd>
</dl>

<p>As mentioned, <span class="file">app/</span> and <span class="file">rho/</span> are normally outside 
the <a href="http://docs.karelia.com/z/Document_Root.html">web server document root</a>.  
The reason being in that it adds a bit of security<sup>[<a href="#fn1">*</a>]</sup>, as these files are never acessed by a client directly.</p>

<h3>Limited Directory Access</h3>
<p>However, if you don't have access outside of the document root on your production server (e.g. cheap shared hosting),
or you are unsure what the production environment will be, then you will have to do the following:</p>
<ol>
  <li>Move <span class="file">app/</span> and <span class="file">rho/</span> so they are inside 
  <span class="file">www/</span>.</li>
  <li>As much as possible, configure the server so these 2 directories are not accessable by a web browser.</li>
  <li>When you write your controller files, you'll need to require core.inc.php like this:
  <pre><code>require_once 'rho/core.inc.php';</code></pre>
  instead of the normal <code>require_once '../rho/core.inc.php';</code>
  <li>Edit <span class="file">www/_dispatch.php</span> so <span class="var">$CORE</span> is correct. E.g.
    <pre><code><span class="var">$CORE</span>='rho/core.inc.php';</code></pre>  
  </li> 
  </li>
</ol>

<p>It's best to do this if necessary at the beginning before you start coding, as it saves pain later on.
Hopefully the production server will be dedicated, virtual, or decent shared hosting, and this will be unnecessary.</p>

<div class="note">
<p>On your development server, where you have lots of sites setup in sub-folders, you'll often create a new directory under the root, e.g.  <span class="file">new_project</span>.
In this case the site will be accessed through the URL <span class="url">http://localhost/new_project/www/</span>.</p>
</div>

<h2>Config and .htaccess</h2>

<p>You'll need to edit the main config file <span class="file">app/conf/core.php</span> and make sure <span class="conf">base_url</span> is set correctly, e.g. <code>http://localhost/new_project/www</code>.
</p>

<p>Next, assuming you'r running Apache, rename <span class="file">www/sample.htaccess</span> to <span class="file">.htaccess</span>.  You'll
need to alter <code>RewriteBase</code> to match your dev environment, e.g. <code>/new_project/www/</code>.
In production, <code>RewriteBase</code> will normally be <code>/</code>.</p>

<p>If your not running Apache, you'll need to convert the rules accordingly for your web server.</p>

<p>If you can't use Mod_Rewrite or equivalent, change <span class="conf">use_rewrite</span> to <code>FALSE</code> in
<span class="file">app/conf/core.php</span>.</p>


<h2>Directory Permissions</h2>

<p>The process that the Web Server/PHP runs as needs write permissions to <span class="file">app/cache/</span>
 and <span class="file">app/logs/</span>.</p>
 
<p>E.g.<br />
<code>chmod 770 ./app/logs<br />
chmod 770 ./app/cache</code></p>


<a name="charset"> </a>
<h2>Character-set Encoding</h2>

<p>Rho uses <strong>UTF-8</strong> encoding through-out.  This means <strong>all source files</strong> must be saved as UTF-8 - check your editor's settings to make sure this is the case.</p>

<p>This also means that your <strong>database</strong> must also be set to use UTF-8.  For example, in mySQL:
<pre><code>CREATE DATABASE `my_app` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;</code>
</pre>
If using an existing database, ensure that all tables are using UTF-8 for text (VARCHAR, CHAR, TEXT, etc.) fields. 
</p>

<h2>Non-Standard PHP File Extension</h2>

<p>On most systems, PHP files end with <span class="file">.php</span>.</p>  In rare circumstances, this may not be the
case - e.g. PHP 4 & PHP 5 running on the same system.  If this is the case, and it can't be changed (e.g. using an Apache directive), then you'll need to do the following:</p>

<ol>
  <li>Your controller files will need to end with the right extension, e.g. <span class="file">.php5</span></li>
  <li>Edit <span class="file">www/_dispatch.php</span> so <span class="var">$EXT</span> is correct. E.g.
    <pre><code><span class="var">$EXT</span>='.php5';</code></pre>  
  </li>  
  <li>Rename <span class="file">www/_dispatch.php</span> accordingly, e.g. <span class="file">_dispatch.php5</span>.</li>
  <li>Edit <span class="file">www/.htaccess</span> so the rewrite rule at the end specifies
   the renamed <span class="file">_dispatch.php</span>. E.g.
   <pre><code>RewriteRule .* _dispatch.php5/$0 [PT,L]</code></pre>
   </li>
   <li>Rename <span class="file">www/rho_test.php</span> accordingly, e.g. <span class="file">rho_test.php5</span>.</li>
</ol>
<p>Other files (libraries, views, etc.) can remain named as they are.</p>

<h2>Test the installation</h2>

<p>Point your web browser to <span class="file">rho_test.php</span>, e.g. 
<span class="url">http://localhost/new_project/www/rho_test.php</span>. </p> 

<p>If everything's correct, you should have a page detailing the Rho installation.</p>

<div class="footnote"><p>
<sup>[<a name="fn1">*</a>]</sup> Assuming the web server doesn't allow 
<span class="url">www.example.com/../../../etc/passwd</span> type URLs...
</div>

<div class="next"><a href="starting.html">Getting Started &gt;&gt;</a></div>
<div id="footer"><p><a href="index.html">Contents</a></p>
<a href="http://code.google.com/p/rho/">Rho Framework Home</a></div>

</body>
</html>